001 /*
002 * Copyright 2001-2005 Stephen Colebourne
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.joda.time;
017
018 /**
019 * Defines an instant in the datetime continuum.
020 * This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z.
021 * <p>
022 * The implementation of this interface may be mutable or immutable.
023 * This interface only gives access to retrieve data, never to change it.
024 * <p>
025 * Methods in your application should be defined using <code>ReadableInstant</code>
026 * as a parameter if the method only wants to read the instant without needing to know
027 * the specific datetime fields.
028 *
029 * @author Stephen Colebourne
030 * @since 1.0
031 */
032 public interface ReadableInstant extends Comparable {
033
034 /**
035 * Get the value as the number of milliseconds since
036 * the epoch, 1970-01-01T00:00:00Z.
037 *
038 * @return the value as milliseconds
039 */
040 long getMillis();
041
042 /**
043 * Gets the chronology of the instant.
044 * <p>
045 * The {@link Chronology} provides conversion from the millisecond
046 * value to meaningful fields in a particular calendar system.
047 *
048 * @return the Chronology, never null
049 */
050 Chronology getChronology();
051
052 /**
053 * Gets the time zone of the instant from the chronology.
054 *
055 * @return the DateTimeZone that the instant is using, never null
056 */
057 DateTimeZone getZone();
058
059 /**
060 * Get the value of one of the fields of a datetime.
061 * <p>
062 * This method uses the chronology of the instant to obtain the value.
063 *
064 * @param type a field type, usually obtained from DateTimeFieldType, not null
065 * @return the value of that field
066 * @throws IllegalArgumentException if the field type is null
067 */
068 int get(DateTimeFieldType type);
069
070 /**
071 * Checks whether the field type specified is supported by this implementation.
072 *
073 * @param field the field type to check, may be null which returns false
074 * @return true if the field is supported
075 */
076 boolean isSupported(DateTimeFieldType field);
077
078 //-----------------------------------------------------------------------
079 /**
080 * Get the value as a simple immutable <code>Instant</code> object.
081 * <p>
082 * This can be useful if you don't trust the implementation
083 * of the interface to be well-behaved, or to get a guaranteed
084 * immutable object.
085 *
086 * @return the value as an <code>Instant</code> object
087 */
088 Instant toInstant();
089
090 //-----------------------------------------------------------------------
091 /**
092 * Compares this object with the specified object for ascending
093 * millisecond instant order. This ordering is inconsistent with
094 * equals, as it ignores the Chronology.
095 * <p>
096 * All ReadableInstant instances are accepted.
097 *
098 * @param readableInstant a readable instant to check against
099 * @return negative value if this is less, 0 if equal, or positive value if greater
100 * @throws NullPointerException if the object is null
101 * @throws ClassCastException if the object type is not supported
102 */
103 int compareTo(Object readableInstant);
104
105 //-----------------------------------------------------------------------
106 /**
107 * Is this instant equal to the instant passed in
108 * comparing solely by millisecond.
109 *
110 * @param instant an instant to check against, null means now
111 * @return true if the instant is equal to the instant passed in
112 */
113 boolean isEqual(ReadableInstant instant);
114
115 /**
116 * Is this instant after the instant passed in
117 * comparing solely by millisecond.
118 *
119 * @param instant an instant to check against, null means now
120 * @return true if the instant is after the instant passed in
121 */
122 boolean isAfter(ReadableInstant instant);
123
124 /**
125 * Is this instant before the instant passed in
126 * comparing solely by millisecond.
127 *
128 * @param instant an instant to check against, null means now
129 * @return true if the instant is before the instant passed in
130 */
131 boolean isBefore(ReadableInstant instant);
132
133 //-----------------------------------------------------------------------
134 /**
135 * Compares this object with the specified object for equality based
136 * on the millisecond instant and the Chronology. All ReadableInstant
137 * instances are accepted.
138 * <p>
139 * To compare two instants for absolute time (ie. UTC milliseconds
140 * ignoring the chronology), use {@link #isEqual(ReadableInstant)} or
141 * {@link #compareTo(Object)}.
142 *
143 * @param readableInstant a readable instant to check against
144 * @return true if millisecond and chronology are equal, false if
145 * not or the instant is null or of an incorrect type
146 */
147 boolean equals(Object readableInstant);
148
149 /**
150 * Gets a hash code for the instant that is compatible with the
151 * equals method.
152 * <p>
153 * The formula used must be as follows:
154 * <pre>
155 * ((int) (getMillis() ^ (getMillis() >>> 32))) +
156 * (getChronology().hashCode())
157 * </pre>
158 *
159 * @return a hash code as defined above
160 */
161 int hashCode();
162
163 //-----------------------------------------------------------------------
164 /**
165 * Get the value as a String in a recognisable ISO8601 format.
166 * <p>
167 * The string output is in ISO8601 format to enable the String
168 * constructor to correctly parse it.
169 *
170 * @return the value as an ISO8601 string
171 */
172 String toString();
173
174 }